The Arsenal Files 8/The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO/g_quake/meddle16.zip/MDL.TXT

Text File | 1996-09-30 | 24KB | 623 lines

-----------------------------------------------------------------------------
MedDLe v1.6
-----------------------------------------------------------------------------

    by brian martin
    [e-mail]
    http://www.phyast.pitt.edu/~brian
    --> also look at http://www.phyast.pitt.edu/~brian/meddle
    for bug fixes and other info.

    Disclaimer: The author takes no responsiblity for misuse of
    this program. He also is not responsible for any damage caused by it.

    This is free software. You can only redistribute it (like on a cdrom)
    after you e-mail me and ask. If you don't e-mail me asking
    permission, you better send me the cd-rom when it's done. Also, you
    can NOT charge money for MedDLe.. it's free remember.

    Last note: If you want the source, mail me. I will give portions of
    it out.



-----------------------------------------------------------------------------
Quick Start:
-----------------------------------------------------------------------------

edit mdl.cfg to fit your needs
run mdl (i.e. "mdl player.mdl")
hit key '1' for help

what's new??
    change screen resolution while viewing (use +/- keys)
    use other config files with -c command line option
    fixed some bugs
    get and set 2dmap in script (maybe not working right?)
    reads/converts qtest models
    writes obj files and  writes geo

-----------------------------------------------------------------------------
Contents:
-----------------------------------------------------------------------------

        1. About MedDLe
        2. Installation
        3. Basic Use
        4. Editing MDL files (step by step)
             4.a Textures
             4.b Frames
        5. Script Language
        6. Notes about file types
        7. History

-----------------------------------------------------------------------------
1. About
-----------------------------------------------------------------------------

MedDLe is a program which lets you look at and edit the mdl
files in quake. These are the files which describe the objects
in quake and are located in the QUAKE\PROGS directory. You have to first
unpack the id1.pak file with a program like unpack or qube. These can both
be found at ftp.cdrom.com.

Features :
        View bitmaps (object textures)
        View/edit point mapping of the vertices
        Export model textures to a BMP or GIF file
        Import BMP or GIF files to give objects a new 'skin'
        Export animation frames to wrl,asc,dxf,pov,map, and raw files
        Import RAW files to make new animations
        Small script language which will allow you to totally screw an mdl
        3D View of object (vertex / wireframe / flatshaded / texture mapped views)
        Animation frame browser
        Played color changer
        .more.

-----------------------------------------------------------------------------
2. Installation
-----------------------------------------------------------------------------

You should stick MedDLe in its own directory. Just unzip it
in a suitable directory (i.e. c:\mdl).  You should have these files
in the MedDLe directory:

    MDL.EXE         -the executable
    MDL.CFG         -the configuration file
    MDL.FNT         -the fonts
    MDL.PAL         -the palette
    MDL.MAP         -the colormap
    KEY.TXT         -quick reference sheet
    MDLSRC.ZIP      -the source code (not with betas)
    CWSDPMI.EXE     -dpmi environment (not needed if in windows)
    EXAMPLE/        -directory with script example(s)

If everything is in place, bring up MDL.CFG in a text editor and set
the path variable and video driver to match your system. You can set
the video resolution here too. When your done, save the file. That's it!

note: You may need a 386/483sx and math co-procesor or a 486dx or higher
to run this. I don't know. There are several math emulators on the net
if it doesn't work on your numerically challenged machine.

-----------------------------------------------------------------------------
3. Basic Use
-----------------------------------------------------------------------------

MedDLe has no GUI at this point. Live with it. :)

MedDLe can both be used to view and edit mdl files. To
start the program just type 'mdl file.mdl' where 'file.mdl'
is a valid mdl filename.

You start in 3D mode.

         ARROW up/down : move eye position up/down
         ARROW left/right : previous/next animation frame

         Esc :        exit
         + or - :    increase / decrease resolution
         2 :            goto 2d mode
         1 :            goto help (about)
         t :            draw triangles
         v :            draw vertices
         s :            TAKE SCREEN SHOT (saved as pic#.bmp)
         h :            show header
         c :            auto cycle through animation frames
         b :            change background color (black, gray, white)
         r :             reset view
         . or > :     next skin
         , or < :        previous skin
         " or ' :        next pants color
         ; or : :        previous pants color
         } or ] :     next shirt color
         { or [ :        previous shirt color
         Tab :        change rendering mode
                    (flat shade, gourourd shade, texture, texture + shade)

         MOUSE up/down + right button : zoom in/out
         MOUSE move + left button : rotate model
         MOUSE move : move light source


Just think of the mouse as your hand grabbing the object. It should
then be easy to control. If you hit the '2' key, you will go to
2D mode. Here the keys are:


         ARROW Keys:     move cursor

         Esc :        exit
         + or - :    increase / decrease resolution
         3 :            goto 3d mode
         1 :            goto help (about)
         t :            draw triangles
         v :            draw vertices
         s :            SAVE MDL FILE
         p :
         m :
         . or > :     next skin
         , or < :        previous skin
         " or ' :        next pants color
         ; or : :        previous pants color
         } or ] :     next shirt color
         { or [ :        previous shirt color

         MOUSE move : move cursor
         MOUSE left button: grab hi-lighted vertex


The mouse can be used to move vertices in this mode.

** NEW **
Command line options of importance.. Now meddle figures out if it's
a skin or frame by the extension.

        import gif (or bmp) to skin number # in model.mdl
        (if # is greater than model skins, skin is added)

            mdl -i pic.gif # model.mdl


        export skin number # to gif (or bmp) from model.mdl
        (if # is 0 or  negetive, a new blank skin with triangles is exported)

            mdl -e pic.gif # model.mdl

        import raw to frame number # in model.mdl

            mdl -i frame.raw # model.mdl


        export frame number # to asc from model.mdl

            mdl -e frame.asc # model.mdl

        run a script file (must have a .med extension)

            mdl script.med


!IMPORTANT!
NOTE: When you use MedDLe, it will read the original mdl files from
the path you set BUT will do all saving and reading from the
current directory. If you load MedDLe in your quake/progs directory,
you may end up erasing something you wish you hadn't. Of course you
can change the read directory in the cfg file, but the save directory
is always the current one.
It may be a hassel, but you'll have to copy the saved mdl to the progs
directory for quake to see the changes (duh).

-----------------------------------------------------------------------------
4. Editing MDL files
-----------------------------------------------------------------------------

I have some info at http://www.phyast.pitt.edu/~brian/meddle but this
ought to help you get started.

4.a Textures

    The following explains the basic proceedure for adding a new skin to
    the player model.

    In this example the 'player.mdl' file is modified with the texture
    'play1.bmp'.

    1. First export the original texture. It will be saved in your
    MedDLe directory.
    'mdl -e play0.bmp 1 player.mdl'
    NOTE: If you want to start from stratch (blank skin), use
    'mdl -e play0.bmp 0 player.mdl'

    2. Now go off and modify the texture in your favorite paint
    program. Make sure you save the new skin with 8-bit color
    in GIF or BMP format. Save the modified texture as 'play1.bmp'
    and place it in your MedDLe directory. The file mdl.pal (included)
    can be loaded into programs like Paint Shop Pro so you can use the
    correct palette, but MedDLe will try to match it up with the quake
    palette if you don't. MedDLe also resizes the picture if necessary.

    3. Import the new texture (play1.bmp).
    'mdl -i play1.bmp 2 player.mdl'
    Since we said '2' it will add the skin in addition to the original
    skin.

    4. Get into 2D mode (hit '2'). You can use the mouse to tweak some
    of the vertices. You want to make sure that you don't change the
    original layout too much, but also want to make sure there is no
    background showing through any of the polygons. You should toggle back
    and forth between 2D mode and 3D mode to check that the texture mapping
    is ok. When your done tweaking, PRESS 's' IN 2D MODE to save your changes.

    Also, you can now change the shirt and pants color to see if you used
    some colors you shouldn't have. Use the " [ ] ; ' " keys to do this.

    NOTE: If you don't press 's' in 2D mode your imported texture
    will NOT be saved!

    5. Copy the new 'player.mdl' file to the quake/progs directory.
    You may want to back up the original 'player.mdl' before doing this.

    6. Run QUAKE!

    Of course the player.mdl is you, so you won't see your changes... :)

** NEW **
4.b Frames

    The following explains the basic proceedure for replacing animation
    frames. In this example the 'player.mdl' file is modified with the
    3d data file 'play1.raw'.

    1. First export the original frame. It will be saved in your
    MedDLe directory.
    'mdl -e play0.raw 1 player.mdl'
    MedDLe will figure out the type of file it is by the extension. So
    'mdl -e play0.asc 1 player.mdl'
    will save it as a 3d studio asc file. Exportable file types are
    pov (POVRay), dxf (cadd type), raw (raw points), asc (ascii),
    map (quake map), wrl (vrml file) and 3ds (3dstudio file).
    The wrl file is the most complete. If you export the skin and convert
    it to a GIF file named 'skin.gif', the wrl file will be texture mapped.
    The 3ds file isn't quite working perfect so use asc if you have 3d studio.
    The raw file can be read by the 3d editor called Breeze Designer which
    is a freeware program which allows vertex editing. I like
    it and recommend it but it does seem to have some bugs if you use it
    to create a model from scratch. The sides don't point out when you create
    say a cube. I wrote the author about this. ClayWorks is another nice
    program but I couldn't input any files to it. I haven't checked out
    bCad much, but it seems to be really nice too. It exports to .asc and
    imports it.. that's good. Also there is a truespace2 demo out there.
    That program is the coolest yet (IMO). You can save the files to
    an ascii format, but MedDLe doesn't read them. A converter to asc or
    raw looks pretty easy, so I may make one up if enough people bother me.

    Remember, to see the frame number of the frames, hit 'h' while in 3d mode.
    Use that number when extracting frames.

    2. Now go off and modify the frame data in your favorite program.
    (like i said, Breeze Designer is nice) Save the modified frame as
    'play1.raw' and place it in your MedDLe directory.

    One word about 3d editing. DON'T CHANGE THE NUMBER OF POINTS IN A FRAME
    IF YOU PLAN ON IMPORTING TO AN EXISTING MDL FILE! JUST MOVE POINTS.
    DON'T ADD OR DELETE POINTS! Making a model from scratch is a different
    story. Read mdl script section below for that.

    3. Import the new frame (play1.raw).
    'mdl -i play1.raw 1 player.mdl'

    4. Get into 2D mode (hit '2'). PRESS 's' IN 2D MODE to save your changes.


    NOTE: If you don't press 's' in 2D mode your new frame won't be saved!

    5. Copy the new 'player.mdl' file to the quake/progs directory.
    You may want to back up the original 'player.mdl' before doing this.

    6. Run QUAKE!


Some added features that a serious editor will use are..

    - the file mdl.pal is used for quake. If you are editing a custom game,
        you can replace mdl.pal with your own palette. The colormap can also
        be changed (mdl.map).
    - if you want to add a skin, just make sure the number is greater that
        the current number of skins (same for frames)
    - if you want to extract a blank skin is a number equal to or less
        than zero.

-----------------------------------------------------------------------------
5. Scripting Language
-----------------------------------------------------------------------------

    There is a small, but powerful scripting language. It is easy to
    use and is the only way to really do serious work. Hopefully
    there are some examples with this distribution.

    The script isn't high tech, so you must use proper syntax. That is,
    you better have a space between words and suff.

    -Anything after a # is ignored.
    -the progspath in the cfg file is NOT used.
    -all script files must have extension .med
    -type "mdl <name>.med" to run the script

    Here are th commands followed by a description. Things in <> are
    necessary arguments:

    path <workingpath>

        this sets the working path <workingpath> for following file io.
        you should end the path with a slash or back-slash (like oj).

    load_mdl <name>

        this will load <name> into MedDLe. You need to load a file
        before you can change things.

    save_mdl <name>

        this saves the current (modified) mdl file to <name>

    new_mdl <frame.name>

        this creates a brand spanking new mdl file. You must supply
        a base frame. A blank skin will be created. Note that the base
        frame usually is not ever going to be used for the model, but
        serves as a template for all of the other frames. The frame is
        stored in the first frame slot.

    get_info <name>

        this outputs some of the model info to a file <name>.

    decompose <medfile> <skin extension> <frame extension>

        this extracts all skins and frames from a model. you must specify
        the file extensions for the extracted data (i.e. gif or bmp for
        <skin extension>). You must also give a med file name which will
        be created to help put things back together. To use the created
        file, make sure to un-comment out the 'save' line at the end of
        the file.

                get_2dmap <filename>

        this outputs the 2d texture coordinate mapping to a text file
        it can be used to help reconstruct models if you have no base
        frame and want to use a quake one.

    2dmap <filename>

        sets the 2d point mapping according to the 2dmap file given

    add <filename>

        adds <filename> to the current loaded model

    insert <filename> <index>

        inserts <filename> to the current loaded model in position <index>

    extract <filename> <index>

        extracts frame or skin number <index> to <filename>

    set <data_type> <value>

        sets certain header values in the model. the valid data types are:
        (these are floating point values)
            xscale, yscale, zscale, xoffset, yoffset, zoffset
            eyex, eyey, eyez
            average_size, radius
        (these are unsigned integer values)
            version, num_skins, num_frames, num_vertices,
            skin_width, skin_height, sync_type, flags
        if you don't know what your doing you can really screw things up here.
        this only sets the value, it doesn't modify the data, so changing the
        skin width will most likely just crash quake (and meddle) when you
        try loading a file.

    frame_name <index> <new name>

        this changes the frame <index>'s name to <new name>. Remember that
        with MedDLe all indices start at 1 (not 0).

    (I know I need to add a delete feature as well)
    Here are some examples:

    example 1:

         path c:\quake\progs\    #set path to progs directory
         load_mdl armor.mdl      #load armor model into memory
         path c:\mdl\script\     #set path to script directory
         decompose armor.med gif raw  #extract all of model into script dir
                                                         #save skins in gif format and frames in raw format
                                                         #create a file armor.med which will put the model
                                                         #back together
    example 2:
         path c:\quake\progs\    #set path to progs directory
         load_mdl player.mdl     #load player model into memory
         path c:\pictures\       #set path to pictures directory
         add newskin.bmp         #adds a new skin
         set zscale .1           #squash the model (why? who knows..)
         path c:\quake\progs\    #set path to progs directory
         save_mdl player2.mdl    #save changes to player2.mdl in progs dir

    example 3:
         path c:\quake\progs\    #set path to progs directory
         load_mdl player.mdl     #load player model into memory
         path c:\mdl\            #set path to mdl
         extract frame1.raw 71   #extract frame 71 to frame1.raw in mdl dir
         new_mdl frame1.raw      #generate a new model
         extract skin1.gif 1     #get the blank skin (so we can modify it)
         save_mdl newplay.mdl    #save the new model

    Hope this helps out.
    I should mention that ripping appart existing mdl files with decompose
    and rebuilding them will not produce the original models. Why? you ask.
    Well as I mentioned earlier, a base frame is used to generate the
    texture and mapping. If you just use the first frame of the model,
    you may get crappy results. For instance, the ogre.mdl has a chain
    saw which won't generate a nice mdl. So what do you do? I think this
    is what id did: You create your objects (ogre and chainsaw) separately
    and then place them in the model file such that they are facing in
    the x direction and are fairly symmetric about the y axis. (z points up).
    Then generate a model with that frame. You can then move the chain saw to
    the hand of the ogre in the other frames. So the script may look like:

        new_mdl base.raw
        insert frame1.raw

    instead of just:

        new_mdl frame2.raw

    Now you may still have some problem getting the texture map to show
    all sides of the chainsaw (or any square object for that matter). In
    this case you should rotate the object around it's y axis 45 degrees
    in the base frame. This will expose the sides of object better in
    some cases. Because of all these little tricks, you can't just
    expect to make the player.mdl from decompose. (you'll have to move
    things so that the gun, axe, and fire flash generate a nice base skin).

    If you make a model from scratch, you should keep in mind that
    your probably using a PC, not a CRAY. KISS. Keep It Simple Stupid.
    Between 1 and 500 triangles is good. Also remember that the models
    only have a resolution of 255x255x255 in discrete units, but are scaled.
    The typical height of a model (in your editors coordinates) is
    about 70. and monsters like the ogre is over 100. Models face in the
    x direction, z is up, and y to the models left. They should be centered
    about the origin, but this can be changed later using the 'set'
    command. Also try to keep all the frame sizes about the same. You'll
    find out that if you make the base frame too different, things will
    be screwed.
    Is that good enough for now?

    One last note. Because MedDLe wasn't written with speed in mind
    when it comes to import/extract, things get slower and slower the
    more frames you add. It should't crash though.
                I take that back. Another note: you may want to pipe the out put
                from the script to a file : "mdl script.med > out.txt"

-----------------------------------------------------------------------------
6. Notes about file types
-----------------------------------------------------------------------------

    Since there is a lot of file importing and exporting going on,
    I decided to say say a little about each file type.

    For the pictures, there is not much to say except to keep
    the colors to 8-bit (256 color). GIF and BMP are supported
    and are color matched and resized when imported.

    Now the 3d files. Since it seems like every editor interperates
    the 3d coordinates differently...

                RAW: this file is just ascii numbers. the first 3 are the x,y,z
                coordinates of the first vertex in the first triangle. The next 3
                are the second vertex of the first triangle. The third set of 3
                are the last vertex. The vertices are arranged such that the
                surface normal points out (counter clockwise). (or maybe it points
                in, can't remember.. just don't change the order). You can use a text
                editor to create models with this format.

                ASC: this is a text format saved by 3d Studio. The coordinate
                system in 3d studio is a bit different from quake. In quake,
                z points up, in 3ds it points towards you. I fixed MedDLe such that
                if you export an asc file, 3d Studio will display it properly,
                but the coordinates are different. (so to convert an exported RAW
                to an ASC and then import may screw things). By properly, I mean
                the 'front' view is the front, the 'left' is the left, etc...
                Importing an asc file works the same. The front remains the front,
                but the x y z values are changed around behind your back. You can
                also create this file by hand. I just want to warn you that here the
                vertices are stored in opposite order from the raw file.

                Those two formats allow import/export of frames and model generation.
                The other formats are just export for now. I haven't had a chance to
                really test them, but the WRL works nicely. Again I had to change
                the coordinate system to get things to look ok, but don't worry
                about it for now. The export of the quake MAP format is a little
                different. This is because it exports the model in the raw byte
                format, that is, each x,y,z value ranges from 0 to 255. I did this
                because I didn't see a quake map editor taking any negative values.
                When a really good map editor is out, I'll fix the import function
                for this. The other file types are DXF and POV. Which I haven't
                had a chance to test.

-----------------------------------------------------------------------------
7. History
-----------------------------------------------------------------------------
v1.6
    -fixed small bugs
    -multiple config files
    -change resolution on the fly
    -maybe last dos version?....
v1.5
    -3d export added and some import
    -script language
    -gif support
v1.4
    -fixed import/export- now its rocks
    -shirt/pants color changing
    -multi skins handled better
    -saving enabled
    -some new key mappings
v1.3
    -includes source with public release
    -gouraud shading with colormap
    -new file format support
    -help screens
    -more comments in source and some cleaning
v1.2
    -released with source
    -better mouse control
v1.1
    -not released-gui experiments
    -gouraud shading
v1.0
    -now you can edit the 2d vertices
    -fixed bugs which caused crashes in 3d mode
    -expanded video support via GRX20
    -added flat shading to 3d models and texture mapping
    -you can now cycle through the frames of animation
    -several other little things
v0.1
    -added wire frame 3d view
    -added importing/exporting BMP files
v0.00002
    - same as v0.00001 but with correct palette
v0.00001 (not released, except on IRC)
    - displayed the skin texture

Wish list..

    -stick man... you'll see
    -gui
    -more time

------------------------------------------------------------------------------

Programmers Note: in this version GRX20 was used along with 3DGPL.
I sorta merged the two together and stuck some of my own stuff in there.
The program is not optimized at all, and a sharp eye will notice that
there is no _perspective_ texture mapping. Oh well, maybe I'll get around
to that in a later version. Or maybe not.

Special thanks goes out to...

Gershon Elber for the source to gif-lib (which I completely trashed)
John Carmack for release of utility source
Chris Babcock for making me aware of the frame data
Raphael Quinet and Sean Werkema for giving out their source which
    made learning to read BMP files easy (also the source taught me a few tricks)
Sergei Savchenko for 3DGPL. I learned a lot of 3D programming from that and
    use several modified versions of his routines for clipping and texture mapping.
DJGPP v2 and the excellent GRX20 graphics lib.
Id for quake.
Becky for putting up with me :)

-end document------------------------------------------------------------------